feat: KYC controller#9615
Conversation
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
Akaryatrh
changed the title
ac34b99 to
a61e704
Compare
|
Review the following changes in direct dependencies. Learn more about Socket for GitHub.
|
|
Warning MetaMask internal reviewing guidelines:
Ignoring alerts on:
|
| * (disclaimers, kyc-required) expect alpha-3 codes (e.g. "USA"). This map | ||
| * bridges the two. | ||
| */ | ||
| export const ALPHA2_TO_ALPHA3: Record<string, string> = { |
There was a problem hiding this comment.
thoughts on this living in a different package or in the client for now?
I think the KYC Controller interface should expect the country code to be in 3 character format
|
@SocketSecurity ignore npm/yargs@17.7.3 |
|
@metamaskbot publish-preview |
Signed-off-by: Sébastien Van Eyck <sebastien.vaneyck@consensys.net>
Signed-off-by: Sébastien Van Eyck <sebastien.vaneyck@consensys.net>
…b flow opening Signed-off-by: Sébastien Van Eyck <sebastien.vaneyck@consensys.net>
Signed-off-by: Sébastien Van Eyck <sebastien.vaneyck@consensys.net>
Signed-off-by: Sébastien Van Eyck <sebastien.vaneyck@consensys.net>
Signed-off-by: Sébastien Van Eyck <sebastien.vaneyck@consensys.net>
Signed-off-by: Sébastien Van Eyck <sebastien.vaneyck@consensys.net>
… been reset Signed-off-by: Sébastien Van Eyck <sebastien.vaneyck@consensys.net>
Signed-off-by: Sébastien Van Eyck <sebastien.vaneyck@consensys.net>
Signed-off-by: Sébastien Van Eyck <sebastien.vaneyck@consensys.net>
Signed-off-by: Sébastien Van Eyck <sebastien.vaneyck@consensys.net>
Signed-off-by: Sébastien Van Eyck <sebastien.vaneyck@consensys.net>
Signed-off-by: Sébastien Van Eyck <sebastien.vaneyck@consensys.net>
Signed-off-by: Sébastien Van Eyck <sebastien.vaneyck@consensys.net>
Signed-off-by: Sébastien Van Eyck <sebastien.vaneyck@consensys.net>
11d7853 to
194d216
Compare
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 2 potential issues.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit 194d216. Configure here.
|
Preview builds have been published. Learn how to use preview builds in other projects. Expand for full list of packages and versions. |
Signed-off-by: Sébastien Van Eyck <sebastien.vaneyck@consensys.net>
Signed-off-by: Sébastien Van Eyck <sebastien.vaneyck@consensys.net>
Signed-off-by: Sébastien Van Eyck <sebastien.vaneyck@consensys.net>
Signed-off-by: Sébastien Van Eyck <sebastien.vaneyck@consensys.net>
2 participants
@metamask/kyc-controllerOverview
@metamask/kyc-controlleris a shared, platform-agnostic KYC / identity-verification package for MetaMask clients (mobile, extension, web). It centralizes all KYC orchestration logic in thecoremonorepo so every client consumes one implementation instead of maintaining its own.What's included
Core modules
KycController(src/KycController.ts) — ABaseControllerthat owns the entire identity flow:idle → terms → session → check → auth → form → submit → done / error.blocks.moonpay.com) over dedicated channels (ch_1,ch_2,ch_reset).KycSumSubLauncheradapter, keeping the controller SDK-free while each client injects its own launcher.product(ramps|card) passed toinitialize/acceptTermsAndStartSessionis stored asactiveProduct. Once authentication reaches theformphase, the controller automatically runs the KYC-required check and, when KYC is required, chains into the SumSub sub-flow — with no extra consumer calls. Without aproduct, the flow stops atformfor manual control (checkKycRequired/startSumSub).KycService(src/KycService.ts) — A data service that performs the Universal KYC (UKYC) HTTP calls via an injectedfetch. It wraps requests withcreateServicePolicyfor resilience, validates responses withsuperstruct, and sources the auth bearer token (fromprofile-sync-controller) and geolocation (fromgeolocation-controller) through the messenger. It also accepts an optionalbaseUrlto override theenv-derived URL for local/staging APIs.Supporting modules
crypto.ts— X25519 key-pair generation and encrypted-credential decryption.countryCodes.ts— ISO 3166-1 alpha-2 → alpha-3 country-code mapping.selectors.ts— Memoized state selectors (selectKycPhase,selectKycSumSub,selectIsKycRequiredForProduct).types.ts— Shared vendor-neutral types (KycPhase,KycProduct,KycVendor,KycSumSubLauncher,KycDisclaimer, etc.).KycController-method-action-types.ts/KycService-method-action-types.ts— Messenger action type definitions for the controller and service.index.ts— Explicit (non-barrel) exports defining the package's public API.Tests
Comprehensive Jest test suites covering the controller, service, crypto, country codes, selectors, and the index/public API (
KycController.tsat 100% coverage, including the new auto-continuation paths).Package scaffolding & monorepo wiring
package.json,tsconfig.json,tsconfig.build.json,jest.config.js,typedoc.json,CHANGELOG.md,README.md, and theLICENSE,LICENSE.APACHE2, andLICENSE.MITfiles.tsconfig.json/tsconfig.build.jsonproject references, added to the rootREADME.mdpackage list, and reflected inyarn.lock.Public API
The package explicitly exports:
KycController,getDefaultKycControllerState,controllerName, plus its messenger, options, state, action, and event types.initialize/acceptTermsAndStartSessionaccept an optionalproductto enable the automatic post-authentication continuation.KycService,serviceName, plus its messenger, options, params, response, action, and event types.selectIsKycRequiredForProduct,selectKycPhase,selectKycSumSub.alpha2ToAlpha3,ALPHA2_TO_ALPHA3,decryptCredentials,generateKeyPair, and related crypto/domain types.Note
The SumSub sub-flow currently uses placeholders (
MOCK_JWT_TOKENand a hardcodedvendorUserId), which must be replaced with real UKYC-issued credentials before production use.Checklist
Note
Medium Risk
New identity/KYC path handles bearer tokens, decrypted frame credentials, and persisted terms/cache; production readiness depends on replacing mock UKYC JWT/vendor IDs and correct client frame-origin handling.
Overview
Introduces
@metamask/kyc-controller, a new monorepo package that centralizes KYC / identity verification for MetaMask clients behind a vendor-neutralramps/cardproduct surface.KycControllerorchestrates the full flow (terms → MoonPay session → Check/Auth frames → optional KYC check → SumSub document verification), including framepostMessagehandling, X25519 + AES-GCM credential decryption, generation guards soreset()does not apply stale async results, and optionalproductoninitialize/acceptTermsAndStartSessionso post-auth KYC check and SumSub can run automatically.KycServiceis a stateless UKYC HTTP client (bearer token + geolocation via messenger, superstruct validation, optionalbaseUrloverride). SumSub UI is injected throughKycSumSubLauncher.Also adds package scaffolding (tests at 100% coverage threshold, README, licenses), root
README/ dependency graph entries, and CODEOWNERS /codeowners.tsfor @MetaMask/universal-kyc. Note: SumSub UKYC session creation still uses placeholders (MOCK_JWT_TOKEN, hardcodedvendorUserId) until real credentials are wired.Reviewed by Cursor Bugbot for commit 2c4805d. Bugbot is set up for automated code reviews on this repo. Configure here.